Summary

TypeScript proof-of-concept for the plugin transformation interface under @common-grants/sdk/extensions, mirroring the Python PoC (#810) so the ADR-0022 / ADR-0017 contract is validated in both SDKs. Ships buildTransforms(), TransformResult<T>, PluginError, the mapping runtime, a definePlugin() extension for meta + transformSchemas, and a runnable round-trip example.

• Fixes [TSX SDK] Draft transforms PoC: TypeScript #798
• Time to review: 15 minutes

Changes proposed

New public surface under @common-grants/sdk/extensions:

• buildTransforms() — compiles a pair of ADR-0017 mapping objects into typed (toCommon, fromCommon) callables with call-time structural validation. Optional commonModel Zod schema turns parse failures into PluginError[] instead of thrown exceptions.
• TransformResult<T> — unconditional { result, errors } return shape (ADR-0022 Decision ADR - Specification framework #7).
• PluginError — structured error carrying path, handler, sourceValue, cause (ADR-0022 Decision ADR - Website hosting #9). sourceValue and cause are plain enumerable fields; per Decision ADR - Website hosting #9, the SDK does not redact by default. Adopters apply a redacted projection ({ name, message, path, handler }, documented in the README) before logging. message is also data-bearing on the Zod-validation path because Zod's default error map embeds rejected runtime values; full-message sanitization is tracked under [Py SDK] Implement plugin-output + mapping-definition validation #744.
• transformFromMapping(), getFromPath(), DEFAULT_HANDLERS — mapping runtime, six built-in handlers (const, field, match, switch alias, numberToString, stringToNumber).
• definePlugin() accepts optional meta: PluginMeta and transformSchemas: Partial<Record<ExtensibleSchemaName, ObjectSchemasInput>>. Existing callers passing only extensions are unaffected.
• New supporting types: Handler, ObjectSchemasInput, ObjectSchemas, PluginMeta, PluginCapability, ObjectMappings, PluginExtensionsObjectConfig, PluginExtensions, TransformSchemasInput.

Behavior changes from a post-PoC review iteration (each surfaces a typo'd mapping at the earliest possible point rather than silently producing wrong output):

• switchOnValue (the match / switch handler) throws on a non-object spec — surfaces as PluginError(handler: "match") via the walker. Catches mappings like { match: "literal-where-spec-belongs" } that previously fell through to silent undefined. Python crashes generically via AttributeError on the same input; TS just fails more helpfully.
• stringToNumber rejects empty / whitespace-only strings and integer-shaped strings outside Number.MAX_SAFE_INTEGER. Number("") silently coerces to 0 in JavaScript; large integer-shaped strings silently lose precision ("9999999999999999999" → 1e19). Both surface as PluginError(handler: "stringToNumber") instead.

Security guards (mapping JSON may be reconstituted from untrusted sources via mergeExtensions(), per ADR-0022 Decision #8):

• __proto__ rejected as an output field name at buildTransforms() call time (validateMapping()) and at walk time (transformFromMapping()).
• getFromPath() traverses with Object.prototype.hasOwnProperty.call rather than in, so attacker-controlled field paths cannot resolve to prototype-chain properties.
• Custom handler names that collide with DEFAULT_HANDLERS or shadow Object.prototype keys (constructor, toString, __proto__, etc.) rejected at buildTransforms() call time.
• Recursion depth capped at a shared DEFAULT_MAX_TRANSFORM_DEPTH = 500 for both the build-time validateMapping() walk and the runtime transformFromMapping() walk, so adversarial mapping JSON cannot pass build-time validation only to blow the stack at runtime.
• PluginError PII contract per ADR-0022 Decision ADR - Website hosting #9 — SDK does not redact by default. sourceValue and cause are enumerable and flow through JSON.stringify(err); adopters use the recommended { name, message, path, handler } projection before logging. Tests assert PII flows by default and that the projection contains it.
• stringToNumber's thrown message does not embed the source value (it would otherwise flow into PluginError.message, which is harder to redact than a separate field).
• Handler JSDoc documents two contracts custom-handler authors must respect: don't return objects with a __proto__ key (the walker treats handler return values as opaque), and don't throw Errors with PII in .message (it flows verbatim into PluginError.message).

Out of scope (deferred to full SDK):

• Auto-generation of transforms from declarative extensions.schemas[obj].mappings inside definePlugin() (Decision Publish static site to GitHub pages #6 TODO).
• Always-on commonModel validation inside definePlugin(), opt-in at buildTransforms() for now (Decision ADR - Specification framework #7 TODO).
• Sanitizing Zod's default error map output before it lands in PluginError.message — couples to the validation surface, tracked in [Py SDK] Implement plugin-output + mapping-definition validation #744.
• Defensive output-key rejection of __defineGetter__ / __defineSetter__ / constructor / toString (own-property shadowing rather than pollution; tracked in [Py SDK] Implement plugin-output + mapping-definition validation #744).

Files:

• New: src/extensions/transforms.ts, src/extensions/transformation.ts, examples/transforms.ts, __tests__/extensions/transforms.spec.ts, __tests__/extensions/transformation.spec.ts, .changeset/transforms-poc-typescript.md
• Modified: src/extensions/types.ts (10 new transform types), src/extensions/define-plugin.ts (meta + transformSchemas), src/extensions/index.ts (exports a superset of Python's extensions/__init__.py surface — TS-only types listed in the barrel comment), src/extensions/README.md (new "Plugin transformations" section + API reference table), __tests__/extensions/define-plugin.spec.ts (five new tests), package.json (example:transforms script; ci now chains the example as a smoke step).

Context for reviewers

How verified:

• pnpm run checks — eslint, prettier, tsc --noEmit clean (0 warnings).
• pnpm run test — 448 tests across 24 suites. PoC contributes 39 handler-runtime tests (transformation.spec.ts) including getFromPath prototype-chain safety; 26 buildTransforms tests (transforms.spec.ts) including handler-shadow rejection for __proto__ / toString / default-name collisions beyond field, build-time __proto__ output-field rejection at root and nested positions, fromCommonMapping depth-cap symmetry, sibling-key parity pinning, and PII flow-through + adopter-supplied redacted-projection coverage; and 5 definePlugin tests for meta + transformSchemas.
• pnpm run ci — full chain (checks → build → test → example:transforms). The example:transforms smoke step round-trips a synthetic grants.gov record through toCommon → Zod-validated CommonGrants Opportunity → fromCommon with custom join / split handlers and verified opportunity_number recovery, so example breakage fails CI instead of going unnoticed.

Conform-before-extend. ADR-0022's TypeScript code blocks and the Python PoC at 799-transform-poc-fetch were treated as the spec, transliterated snake_case → camelCase, swapped Pydantic → Zod, and reused existing TS SDK type patterns (const generics, mapped types). Intentional divergences from the ADR's TS shape documented in code comments:

• DefinePluginOptions.transformSchemas (not schemas) mirrors Python's transform_schemas workaround for the collision with the existing Plugin.schemas field. Full SDK target: resolve in [TSX SDK] Extend definePlugin() to accept schemas with toCommon/fromCommon #756.
• BuildTransformsOptions.commonModel: z.ZodType<TCommon, z.ZodTypeDef, any> uses any in the contravariant input position to accept schemas with input/output asymmetry (e.g. .transform() producing Date from string). The ADR's ZodType<TCommon> would reject the SDK's own OpportunityBaseSchema.
• buildTransforms() takes an options object { toCommonMapping, fromCommonMapping, handlers?, commonModel? } rather than the ADR's positional (toCommonMapping, fromCommonMapping, handlers?). Matches definePlugin()'s shape and leaves room for commonModel and future flags. ADR cosmetic update tracked alongside the full SDK work.

Cross-SDK behavior notes vs. Python PoC #810

The two SDKs converge on behavior for all mapping shapes that produce valid output. Where they differ on failure modes, the differences fall into two categories:

Same fail-loud direction, different error quality. Both SDKs reject the input; TS produces a more descriptive error message:

• switchOnValue non-object spec: Python AttributeError on .get(); TS throws Error("match/switch handler: spec must be an object") wrapped as PluginError(handler: "match").
• stringToNumber empty / whitespace string: Python int("") raises ValueError; TS throws a descriptive message via PluginError(handler: "stringToNumber").

JS-specific concerns with no Python analogue. Defenses against attack surfaces that don't exist in Python:

• __proto__ build / walk / scrub defenses (prototype pollution is JS-only).
• Object.prototype-shadow handler-name rejection.
• getFromPath Object.prototype.hasOwnProperty.call over in.
• stringToNumber unsafe-integer rejection (Python ints are arbitrary precision, so no analogous precision-loss concern).

Open ADR question worth surfacing for both SDKs: ADR-0022 Decision #9 says "the SDK does not redact by default." This PR's earlier iteration added non-enumerable + toJSON() hardening to redact sourceValue / cause on the JSON.stringify path; that hardening was removed to align with the ADR text. Worth a separate conversation on whether to amend Decision #9 to allow (or require) default JSON redaction in both SDKs.

Why HOLD-transforms. Issue #798 sits in the transforms feature bucket (#656, #745, #756, #757, #768, #798, #799, #813) per the branching strategy doc. The bucket batches to main at the C2 (July 21) checkpoint. PR #810 already targets HOLD-transforms for the Python PoC.

Additional information

Example output (from pnpm example:transforms):

=== toCommon (native → CommonGrants) ===
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Research into conservation techniques",
  "status": { "value": "open" },
  "customFields": {
    "legacyId":      { "name": "legacyId",      "fieldType": "integer", "value": 12345 },
    "agencyName":    { "name": "agencyName",    "fieldType": "string",  "value": "Department of Examples" },
    "applicantTypes": { "name": "applicantTypes", "fieldType": "array",  "value": ["state_governments"] },
    "compositeLabel": { "name": "compositeLabel", "fieldType": "string", "value": "ABC-123-XYZ-001 — Research into conservation techniques" }
  },
  ...
}

=== fromCommon (CommonGrants → native) ===
{
  "data": {
    "opportunity_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "opportunity_title": "Research into conservation techniques",
    "opportunity_number": "ABC-123-XYZ-001",  // recovered from compositeLabel via split handler
    ...
  }
}

✓ round-trip verified for fields covered by both mappings